Game Programming in C++ - Start to Finish

home *** CD-ROM | disk | FTP | other *** search

/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-Native.exe / {app} / include / elements / CEGUIListHeader.h < prev next >

Wrap

C/C++ Source or Header | 2005-06-04 | 24.6 KB | 852 lines

/************************************************************************ filename: CEGUIListHeader.h created: 13/4/2004 author: Paul D Turner purpose: Interface to base class for ListHeader widget *************************************************************************/ /************************************************************************* Crazy Eddie's GUI System (http://www.cegui.org.uk) Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk) This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *************************************************************************/ #ifndef _CEGUIListHeader_h_ #define _CEGUIListHeader_h_ #include "CEGUIBase.h" #include "CEGUIWindow.h" #include "elements/CEGUIListHeaderSegment.h" #include "elements/CEGUIListHeaderProperties.h" #if defined(_MSC_VER) # pragma warning(push) # pragma warning(disable : 4251) #endif // Start of CEGUI namespace section namespace CEGUI { /*! \brief EventArgs class used for segment move (sequence changed) events. */ class CEGUIEXPORT HeaderSequenceEventArgs : public WindowEventArgs { public: HeaderSequenceEventArgs(Window* wnd, uint old_idx, uint new_idx) : WindowEventArgs(wnd), d_oldIdx(old_idx), d_newIdx(new_idx) {}; uint d_oldIdx; //!< The original column index of the segment that has moved. uint d_newIdx; //!< The new column index of the segment that has moved. }; /*! \brief Base class for the multi column list header widget. */ class CEGUIEXPORT ListHeader : public Window { public: static const String EventNamespace; //!< Namespace for global events /************************************************************************* Constants *************************************************************************/ // Event names static const String EventSortColumnChanged; //!< Event fired when the current sort column changes. static const String EventSortDirectionChanged; //!< Event fired when the sort direction changes. static const String EventSegmentSized; //!< Event fired when a segment has been sized by the user (e.window is the segment). static const String EventSegmentClicked; //!< Event fired when a segment has been clicked by the user (e.window is the segment). static const String EventSplitterDoubleClicked; //!< Event fired when a segment splitter has been double-clicked. (e.window is the segment). static const String EventSegmentSequenceChanged; //!< Event fired when the order of the segments has changed. ('e' is a HeaderSequenceEventArgs&) static const String EventSegmentAdded; //!< Event fired when a segment is added to the header. static const String EventSegmentRemoved; //!< Event fired when a segment is removed from the header. static const String EventSortSettingChanged; //!< Event fired when setting that controls user modification to sort configuration changes. static const String EventDragMoveSettingChanged; //!< Event fired when setting that controls user drag & drop of segments changes. static const String EventDragSizeSettingChanged; //!< Event fired when setting that controls user sizing of segments changes. static const String EventSegmentRenderOffsetChanged; //!< Event fired when the rendering offset for the segments changes. // values static const float ScrollSpeed; //!< Speed to scroll at when dragging outside header. static const float MinimumSegmentPixelWidth; //!< Miniumum width of a segment in pixels. /************************************************************************* Accessor Methods *************************************************************************/ /*! \brief Return the number of columns or segments attached to the header. \return uint value equal to the number of columns / segments currently in the header. */ uint getColumnCount(void) const; /*! \brief Return the ListHeaderSegment object for the specified column \param column zero based column index of the ListHeaderSegment to be returned. \return ListHeaderSegment object at the requested index. \exception InvalidRequestException thrown if column is out of range. */ ListHeaderSegment& getSegmentFromColumn(uint column) const; /*! \brief Return the ListHeaderSegment object with the specified ID. \param id id code of the ListHeaderSegment to be returned. \return ListHeaderSegment object with the ID \a id. If more than one segment has the same ID, only the first one will ever be returned. \exception InvalidRequestException thrown if no segment with the requested ID is attached. */ ListHeaderSegment& getSegmentFromID(uint id) const; /*! \brief Return the ListHeaderSegment that is marked as being the 'sort key' segment. There must be at least one segment to successfully call this method. \return ListHeaderSegment object which is the sort-key segment. \exception InvalidRequestException thrown if no segments are attached to the ListHeader. */ ListHeaderSegment& getSortSegment(void) const; /*! \brief Return the zero based column index of the specified segment. \param segment ListHeaderSegment whos zero based index is to be returned. \return Zero based column index of the ListHeaderSegment \a segment. \exception InvalidRequestException thrown if \a segment is not attached to this ListHeader. */ uint getColumnFromSegment(const ListHeaderSegment& segment) const; /*! \brief Return the zero based column index of the segment with the specified ID. \param id ID code of the segment whos column index is to be returned. \return Zero based column index of the first ListHeaderSegment whos ID matches \a id. \exception InvalidRequestException thrown if no attached segment has the requested ID. */ uint getColumnFromID(uint id) const; /*! \brief Return the zero based index of the current sort column. There must be at least one segment/column to successfully call this method. \return Zero based column index that is the current sort column. \exception InvalidRequestException thrown if there are no segments / columns in this ListHeader. */ uint getSortColumn(void) const; /*! \brief Return the zero based column index of the segment with the specified text. \param text String object containing the text to be searched for. \return Zero based column index of the segment with the specified text. \exception InvalidRequestException thrown if no attached segments have the requested text. */ uint getColumnWithText(const String& text) const; /*! \brief Return the pixel offset to the given ListHeaderSegment. \param segment ListHeaderSegment object that the offset to is to be returned. \return The number of pixels up-to the begining of the ListHeaderSegment described by \a segment. \exception InvalidRequestException thrown if \a segment is not attached to the ListHeader. */ float getPixelOffsetToSegment(const ListHeaderSegment& segment) const; /*! \brief Return the pixel offset to the ListHeaderSegment at the given zero based column index. \param column Zero based column index of the ListHeaderSegment whos pixel offset it to be returned. \return The number of pixels up-to the begining of the ListHeaderSegment located at zero based column index \a column. \exception InvalidRequestException thrown if \a column is out of range. */ float getPixelOffsetToColumn(uint column) const; /*! \brief Return the total pixel width of all attached segments. \return Sum of the pixel widths of all attached ListHeaderSegment objects. */ float getTotalSegmentsPixelExtent(void) const; /*! \brief Return the pixel width of the specified column. \param column Zero based column index of the segment whos pixel width is to be returned. \return Pixel width of the ListHeaderSegment at the zero based column index specified by \a column. \exception InvalidRequestException thrown if \a column is out of range. */ float getColumnPixelWidth(uint column) const; /*! \brief Return the currently set sort direction. \return One of the ListHeaderSegment::SortDirection enumerated values specifying the current sort direction. */ ListHeaderSegment::SortDirection getSortDirection(void) const; /*! \brief Return whether user manipulation of the sort column & direction are enabled. \return true if the user may interactively modify the sort column and direction. false if the user may not modify the sort column and direction (these can still be set programmatically). */ bool isSortingEnabled(void) const; /*! \brief Return whether the user may size column segments. \return true if the user may interactively modify the width of column segments, false if they may not. */ bool isColumnSizingEnabled(void) const; /*! \brief Return whether the user may modify the order of the segments. \return true if the user may interactively modify the order of the column segments, false if they may not. */ bool isColumnDraggingEnabled(void) const; /*! \brief Return the current segment offset value. This value is used to implement scrolling of the header segments within the ListHeader area. \return float value specifying the current segment offset value in whatever metrics system is active for the ListHeader. */ float getSegmentOffset(void) const {return d_segmentOffset;} /************************************************************************* Manipulator Methods *************************************************************************/ /*! \brief Set whether user manipulation of the sort column and direction is enabled. \param setting - true to allow interactive user manipulation of the sort column and direction. - false to disallow interactive user manipulation of the sort column and direction. \return Nothing. */ void setSortingEnabled(bool setting); /*! \brief Set the current sort direction. \param direction One of the ListHeaderSegment::SortDirection enumerated values indicating the sort direction to be used. \return Nothing. */ void setSortDirection(ListHeaderSegment::SortDirection direction); /*! \brief Set the column segment to be used as the sort column. \param segment ListHeaderSegment object indicating the column to be sorted. \return Nothing. \exception InvalidRequestException thrown if \a segment is not attached to this ListHeader. */ void setSortSegment(const ListHeaderSegment& segment); /*! \brief Set the column to be used as the sort column. \param column Zero based column index indicating the column to be sorted. \return Nothing. \exception InvalidRequestException thrown if \a column is out of range for this ListHeader. */ void setSortColumn(uint column); /*! \brief Set the column to to be used for sorting via its ID code. \param id ID code of the column segment that is to be used as the sort column. \return Nothing. \exception InvalidRequestException thrown if no segment with ID \a id is attached to the ListHeader. */ void setSortColumnFromID(uint id); /*! \brief Set whether columns may be sized by the user. \param setting - true to indicate that the user may interactively size segments. - false to indicate that the user may not interactively size segments. \return Nothing. */ void setColumnSizingEnabled(bool setting); /*! \brief Set whether columns may be reordered by the user via drag and drop. \param setting - true to indicate the user may change the order of the column segments via drag and drop. - false to indicate the user may not change the column segment order. \return Nothing. */ void setColumnDraggingEnabled(bool setting); /*! \brief Add a new column segment to the end of the header. \param text String object holding the initial text for the new segment \param id Client specified ID code to be assigned to the new segment. \param width Initial width of the new segment using the relative metrics system \return Nothing. */ void addColumn(const String& text, uint id, float width); /*! \brief Insert a new column segment at the specified position. \param text String object holding the initial text for the new segment \param id Client specified ID code to be assigned to the new segment. \param width Initial width of the new segment using the relative metrics system \param position Zero based column index indicating the desired position for the new column. If this is greater than the current number of columns, the new segment is added to the end if the header. \return Nothing. */ void insertColumn(const String& text, uint id, float width, uint position); /*! \brief Insert a new column segment at the specified position. \param text String object holding the initial text for the new segment \param id Client specified ID code to be assigned to the new segment. \param width Initial width of the new segment using the relative metrics system \param position ListHeaderSegment object indicating the insert position for the new segment. The new segment will be inserted before the segment indicated by \a position. \return Nothing. \exception InvalidRequestException thrown if ListHeaderSegment \a position is not attached to the ListHeader. */ void insertColumn(const String& text, uint id, float width, const ListHeaderSegment& position); /*! \brief Removes a column segment from the ListHeader. \param column Zero based column index indicating the segment to be removed. \return Nothing. \exception InvalidRequestException thrown if \a column is out of range. */ void removeColumn(uint column); /*! \brief Remove the specified segment from the ListHeader. \param segment ListHeaderSegment object that is to be removed from the ListHeader. \return Nothing. \exception InvalidRequestException thrown if \a segment is not attached to this ListHeader. */ void removeSegment(const ListHeaderSegment& segment); /*! \brief Moves a column segment into a new position. \param column Zero based column index indicating the column segment to be moved. \param position Zero based column index indicating the new position for the segment. If this is greater than the current number of segments, the segment is moved to the end of the header. \return Nothing. \exception InvalidRequestException thrown if \a column is out of range for this ListHeader. */ void moveColumn(uint column, uint position); /*! \brief Move a column segment to a new position. \param column Zero based column index indicating the column segment to be moved. \param position ListHeaderSegment object indicating the new position for the segment. The segment at \a column will be moved behind segment \a position (that is, segment \a column will appear to the right of segment \a position). \return Nothing. \exception InvalidRequestException thrown if \a column is out of range for this ListHeader, or if \a position is not attached to this ListHeader. */ void moveColumn(uint column, const ListHeaderSegment& position); /*! \brief Moves a segment into a new position. \param segment ListHeaderSegment object that is to be moved. \param position Zero based column index indicating the new position for the segment. If this is greater than the current number of segments, the segment is moved to the end of the header. \return Nothing. \exception InvalidRequestException thrown if \a segment is not attached to this ListHeader. */ void moveSegment(const ListHeaderSegment& segment, uint position); /*! \brief Move a segment to a new position. \param segment ListHeaderSegment object that is to be moved. \param position ListHeaderSegment object indicating the new position for the segment. The segment \a segment will be moved behind segment \a position (that is, segment \a segment will appear to the right of segment \a position). \return Nothing. \exception InvalidRequestException thrown if either \a segment or \a position are not attached to this ListHeader. */ void moveSegment(const ListHeaderSegment& segment, const ListHeaderSegment& position); /*! \brief Set the current base segment offset. (This implements scrolling of the header segments within the header area). \param offset New base offset for the first segment. The segments will of offset to the left by the amount specified. \a offset should be specified using the active metrics system for the ListHeader. \return Nothing. */ void setSegmentOffset(float offset); /*! \brief Set the pixel width of the specified column. \param column Zero based column index of the segment whos pixel width is to be set. \param width float value specifying the new pixel width to set for the ListHeaderSegment at the zero based column index specified by \a column. \return Nothing \exception InvalidRequestException thrown if \a column is out of range. */ void setColumnPixelWidth(uint column, float width); /************************************************************************* Construction and Destruction *************************************************************************/ /*! \brief Constructor for the list header base class. */ ListHeader(const String& type, const String& name); /*! \brief Destructor for the list header base class. */ virtual ~ListHeader(void); protected: /************************************************************************* Abstract Implementation Methods *************************************************************************/ /*! \brief Create and return a pointer to a new ListHeaderSegment based object. \param name String object holding the name that should be given to the new Window. \return Pointer to an ListHeaderSegment based object of whatever type is appropriate for this ListHeader. */ virtual ListHeaderSegment* createNewSegment(const String& name) const = 0; /*! \brief Cleanup and destroy the given ListHeaderSegment that was created via the createNewSegment method. \param segment Pointer to a ListHeaderSegment based object to be destroyed. \return Nothing. */ virtual void destroyListSegment(ListHeaderSegment* segment) const = 0; /************************************************************************* Implementation Methods *************************************************************************/ /*! \brief Create initialise and return a ListHeaderSegment object, with all events subscribed and ready to use. */ ListHeaderSegment* createInitialisedSegment(const String& text, uint id, float width); /*! \brief Layout the attached segments */ void layoutSegments(void); /*! \brief Add ListHeader specific events */ void addListHeaderEvents(void); /*! \brief Return whether this window was inherited from the given class name at some point in the inheritance heirarchy. \param class_name The class name that is to be checked. \return true if this window was inherited from \a class_name. false if not. */ virtual bool testClassName_impl(const String& class_name) const { if (class_name==(const utf8*)"ListHeader") return true; return Window::testClassName_impl(class_name); } /************************************************************************* New List header event handlers *************************************************************************/ /*! \brief Handler called when the sort column is changed. */ virtual void onSortColumnChanged(WindowEventArgs& e); /*! \brief Handler called when the sort direction is changed. */ virtual void onSortDirectionChanged(WindowEventArgs& e); /*! \brief Handler called when a segment is sized by the user. e.window points to the segment. */ virtual void onSegmentSized(WindowEventArgs& e); /*! \brief Handler called when a segment is clicked by the user. e.window points to the segment. */ virtual void onSegmentClicked(WindowEventArgs& e); /*! \brief Handler called when a segment splitter / sizer is double-clicked. e.window points to the segment. */ virtual void onSplitterDoubleClicked(WindowEventArgs& e); /*! \brief Handler called when the segment / column order changes. */ virtual void onSegmentSequenceChanged(WindowEventArgs& e); /*! \brief Handler called when a new segment is added to the header. */ virtual void onSegmentAdded(WindowEventArgs& e); /*! \brief Handler called when a segment is removed from the header. */ virtual void onSegmentRemoved(WindowEventArgs& e); /*! \brief Handler called then setting that controls the users ability to modify the search column & direction changes. */ virtual void onSortSettingChanged(WindowEventArgs& e); /*! \brief Handler called when the setting that controls the users ability to drag and drop segments changes. */ virtual void onDragMoveSettingChanged(WindowEventArgs& e); /*! \brief Handler called when the setting that controls the users ability to size segments changes. */ virtual void onDragSizeSettingChanged(WindowEventArgs& e); /*! \brief Handler called when the base rendering offset for the segments (scroll position) changes. */ virtual void onSegmentOffsetChanged(WindowEventArgs& e); /************************************************************************* handlers for events we subscribe to from segments *************************************************************************/ bool segmentSizedHandler(const EventArgs& e); bool segmentMovedHandler(const EventArgs& e); bool segmentClickedHandler(const EventArgs& e); bool segmentDoubleClickHandler(const EventArgs& e); bool segmentDragHandler(const EventArgs& e); /************************************************************************* Implementation Data *************************************************************************/ typedef std::vector<ListHeaderSegment*> SegmentList; SegmentList d_segments; //!< Attached segment windows in header order. ListHeaderSegment* d_sortSegment; //!< Pointer to the segment that is currently set as the sork-key, bool d_sizingEnabled; //!< true if segments can be sized by the user. bool d_sortingEnabled; //!< true if the sort criteria modifications by user are enabled (no sorting is actuall done) bool d_movingEnabled; //!< true if drag & drop moving of columns / segments is enabled. uint d_uniqueIDNumber; //!< field used to create unique names. float d_segmentOffset; //!< Base offset used to layout the segments (allows scrolling within the window area) ListHeaderSegment::SortDirection d_sortDir; //!< Brief copy of the current sort direction. private: /************************************************************************* Static Properties for this class *************************************************************************/ static ListHeaderProperties::SortSettingEnabled d_sortSettingProperty; static ListHeaderProperties::ColumnsSizable d_sizableProperty; static ListHeaderProperties::ColumnsMovable d_movableProperty; static ListHeaderProperties::SortColumnID d_sortColumnIDProperty; static ListHeaderProperties::SortDirection d_sortDirectionProperty; /************************************************************************* Private methods *************************************************************************/ void addHeaderProperties(void); }; } // End of CEGUI namespace section #if defined(_MSC_VER) # pragma warning(pop) #endif #endif // end of guard _CEGUIListHeader_h_